<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
    <title>schur</title>
  </head>
  <body bgcolor="#FFFFFF">
    <center>Scilab Function</center>
    <div align="right">Last update : 20/12/2004</div>
    <p>
      <b>schur</b> -  [ordered] Schur decomposition of matrix and pencils</p>
    <h3>
      <font color="blue">Calling Sequence</font>
    </h3>
    <dl>
      <dd>
        <tt>[U,T] = schur(A)   </tt>
      </dd>
      <dd>
        <tt>[U,dim [,T] ]=schur(A,flag)  </tt>
      </dd>
      <dd>
        <tt>[U,dim [,T] ]=schur(A,extern1)  </tt>
      </dd>
      <dd>
        <tt></tt>
      </dd>
      <dd>
        <tt>[As,Es [,Q,Z]]=schur(A,E)  </tt>
      </dd>
      <dd>
        <tt>[As,Es [,Q],Z,dim] = schur(A,E,flag)   </tt>
      </dd>
      <dd>
        <tt>[Z,dim] = schur(A,E,flag)   </tt>
      </dd>
      <dd>
        <tt>[As,Es [,Q],Z,dim]= schur(A,E,extern2)  </tt>
      </dd>
      <dd>
        <tt>[Z,dim]= schur(A,E,extern2)  </tt>
      </dd>
    </dl>
    <h3>
      <font color="blue">Parameters</font>
    </h3>
    <ul>
      <li>
        <tt>
          <b>A</b>
        </tt>: real or complex square matrix.</li>
      <li>
        <tt>
          <b>E</b>
        </tt>: real or complex square matrix with same dimensions as <tt>
          <b> A</b>
        </tt>.</li>
      <li>
        <tt>
          <b>flag</b>
        </tt>: character string (<tt>
          <b>'c'</b>
        </tt> or <tt>
          <b>'d'</b>
        </tt>)</li>
      <li>
        <tt>
          <b>extern1</b>
        </tt>: an ``external'', see below</li>
      <li>
        <tt>
          <b>extern2</b>
        </tt>: an ``external'', see below</li>
      <li>
        <tt>
          <b>U</b>
        </tt>: orthogonal or unitary square matrix</li>
      <li>
        <tt>
          <b>Q</b>
        </tt>: orthogonal or unitary square matrix</li>
      <li>
        <tt>
          <b>Z</b>
        </tt>: orthogonal or unitary square matrix</li>
      <li>
        <tt>
          <b>T</b>
        </tt>: upper triangular or quasi-triangular square matrix</li>
      <li>
        <tt>
          <b>As</b>
        </tt>: upper triangular or quasi-triangular square matrix</li>
      <li>
        <tt>
          <b>Es</b>
        </tt>: upper triangular  square matrix</li>
      <li>
        <tt>
          <b>dim</b>
        </tt>: integer</li>
    </ul>
    <h3>
      <font color="blue">Description</font>
    </h3>
    <p>
    Schur forms, ordered Schur forms of matrices and pencils
  </p>
    <dl>
      <dd>
        <b>MATRIX SCHUR FORM</b>
        <dl>
          <dd>
            <b>Usual schur form:</b>
            <p>
              <tt>
                <b>[U,T] = schur(A)</b>
              </tt> produces a Schur matrix
        <tt>
                <b>T</b>
              </tt> and a unitary matrix <tt>
                <b>U</b>
              </tt> so that
        <tt>
                <b>A = U*T*U'</b>
              </tt> and <tt>
                <b>U'*U =  eye(U)</b>
              </tt>. By itself, schur(<tt>
                <b>A</b>
              </tt>) returns
        <tt>
                <b>T</b>
              </tt>. If <tt>
                <b>A</b>
              </tt> is complex, the Complex
        Schur Form is returned in matrix
	<tt>
                <b>T</b>
              </tt>. The Complex Schur Form is upper triangular with
	the eigenvalues of <tt>
                <b>A</b>
              </tt> on the diagonal. If
	<tt>
                <b>A</b>
              </tt> is real, the Real Schur Form is returned.  The Real
	Schur Form has the real eigenvalues on the diagonal and the
	complex eigenvalues in 2-by-2 blocks on the diagonal.
      </p>
          </dd>
          <dd>
            <b>Ordered Schur forms</b>
            <tt>
              <b>[U,dim]=schur(A,'c')</b>
            </tt> returns an unitary
      matrix <tt>
              <b>U</b>
            </tt> which transforms <tt>
              <b>A</b>
            </tt> into schur
      form.  In addition, the dim first columns of <tt>
              <b>U</b>
            </tt> make
      a basis of the eigenspace of <tt>
              <b>A</b>
            </tt> associated with
      eigenvalues with negative real parts (stable "continuous
      time" eigenspace).<p>
              <tt>
                <b>[U,dim]=schur(A,'d')</b>
              </tt> returns an unitary
      matrix <tt>
                <b>U</b>
              </tt> which transforms <tt>
                <b>A</b>
              </tt> into schur
      form.  In addition, the <tt>
                <b>dim</b>
              </tt> first columns of
      <tt>
                <b>U</b>
              </tt> span a basis of the eigenspace of <tt>
                <b>A</b>
              </tt>
      associated with eigenvalues with magnitude lower than 1 (stable
      "discrete time" eigenspace).
      </p>
            <p>
              <tt>
                <b>[U,dim]=schur(A,extern1)</b>
              </tt> returns an unitary matrix
      <tt>
                <b>U</b>
              </tt> which transforms <tt>
                <b>A</b>
              </tt> into schur form.
      In addition, the <tt>
                <b>dim</b>
              </tt> first columns of
      <tt>
                <b>U</b>
              </tt> span a basis of the eigenspace of <tt>
                <b>A</b>
              </tt>
      associated with the eigenvalues which are selected by the
      external function <tt>
                <b>extern1</b>
              </tt> (see external for
      details).  This external can be described by a Scilab function
      or by C or Fortran procedure: </p>
            <dl>
              <dd>
                <b>a Scilab function</b>If <tt>
                  <b>extern1</b>
                </tt> is described by a Scilab function, it
	  should have the following calling sequence:
	  <tt>
                  <b>s=extern1(Ev)</b>
                </tt>, where <tt>
                  <b>Ev</b>
                </tt> is an eigenvalue and
	  <tt>
                  <b>s</b>
                </tt> a boolean.</dd>
              <dd>
                <b>a C or Fortran procedure</b>If <tt>
                  <b>extern1</b>
                </tt> is described by a C or Fortran function it
	  should have the following calling sequence:
	  <tt>
                  <b>int extern1(double *EvR, double *EvI)</b>
                </tt>
	  where <tt>
                  <b>EvR</b>
                </tt> and <tt>
                  <b>EvI</b>
                </tt> are  eigenvalue real and complex parts.
	  a true or non zero returned value stands for selected eigenvalue.</dd>
            </dl>
          </dd>
        </dl>
      </dd>
      <dd>
        <b>PENCIL SCHUR FORMS</b>
        <dl>
          <dd>
            <b>Usual Pencil Schur form</b>
            <tt>
              <b>[As,Es] = schur(A,E)</b>
            </tt> produces a quasi triangular
      <tt>
              <b>As</b>
            </tt> matrix and a triangular <tt>
              <b>Es</b>
            </tt> matrix
      which are the generalized Schur form of the pair <tt>
              <b>A, E</b>
            </tt>.<p>
              <tt>
                <b>[As,Es,Q,Z] = schur(A,E)</b>
              </tt>
      returns in addition two unitary matrices
      <tt>
                <b>Q</b>
              </tt> and <tt>
                <b>Z</b>
              </tt> such that
      <tt>
                <b>As=Q'*A*Z</b>
              </tt> and <tt>
                <b>Es=Q'*E*Z</b>
              </tt>.
      </p>
          </dd>
          <dd>
            <b>Ordered Schur forms:</b>
            <tt>
              <b>[As,Es,Z,dim] = schur(A,E,'c')</b>
            </tt>
      returns the real generalized
      Schur form of the pencil <tt>
              <b>s*E-A</b>
            </tt>. In addition, the dim first columns 
      of <tt>
              <b>Z</b>
            </tt> span a basis of the right eigenspace  associated with 
      eigenvalues with negative real parts (stable "continuous
      time" generalized eigenspace).<p>
              <tt>
                <b>[As,Es,Z,dim] = schur(A,E,'d')</b>
              </tt>
            </p>
            <p>
      returns the real generalized
      Schur form of the pencil <tt>
                <b>s*E-A</b>
              </tt>. In addition, the dim first columns 
      of <tt>
                <b>Z</b>
              </tt> make a basis of the right eigenspace  associated with 
      eigenvalues with magnitude lower than 1 (stable "discrete
      time" generalized eigenspace).
      </p>
            <p>
              <tt>
                <b>[As,Es,Z,dim] = schur(A,E,extern2)</b>
              </tt>
            </p>
            <p>
      returns the real generalized Schur form of the pencil <tt>
                <b>s*E-A</b>
              </tt>. 
      In addition, the dim first columns 
      of <tt>
                <b>Z</b>
              </tt> make a basis of the right eigenspace  associated with 
      eigenvalues of the pencil which are selected according to a
      rule which is given by the function <tt>
                <b>extern2</b>
              </tt>. (see external
      for details). This external can be described by a Scilab
      function or by C or Fortran procedure:      </p>
            <dl>
              <dd>
                <b>A Scilab function</b>If <tt>
                  <b>extern2</b>
                </tt> is described by a Scilab function, it should
	  have the following calling sequence:
	  <tt>
                  <b>s=extern2(Alpha,Beta)</b>
                </tt>, where <tt>
                  <b>Alpha</b>
                </tt> and
	  <tt>
                  <b>Beta</b>
                </tt> defines a generalized eigenvalue and
	  <tt>
                  <b>s</b>
                </tt> a boolean.</dd>
              <dd>
                <b>C or Fortran procedure</b>if external <tt>
                  <b>extern2</b>
                </tt> is described by a C or a
	  Fortran procedure, it should have the following calling
	  sequence:<p>
                  <tt>
                    <b>int extern2(double *AlphaR, double *AlphaI, double *Beta)</b>
                  </tt>
                </p>
                <p>
	  if <tt>
                    <b>A</b>
                  </tt> and <tt>
                    <b>E</b>
                  </tt> are real and</p>
                <p>
                  <tt>
                    <b>int extern2(double *AlphaR, double *AlphaI, double *BetaR, double *BetaI)</b>
                  </tt>
                </p>
                <p>
	  if <tt>
                    <b>A</b>
                  </tt> or <tt>
                    <b>E</b>
                  </tt> are complex.
	  <tt>
                    <b>Alpha</b>
                  </tt>, and <tt>
                    <b>Beta</b>
                  </tt> defines the generalized eigenvalue.
	  a true or non zero returned value stands for selected generalized eigenvalue.</p>
              </dd>
            </dl>
          </dd>
        </dl>
      </dd>
    </dl>
    <h3>
      <font color="blue">References</font>
    </h3>
    <dl>
      <p>
    Matrix schur form computations are based on the Lapack routines DGEES and ZGEES.</p>
      <p>
    Pencil schur form computations are based on the Lapack routines DGGES and ZGGES.</p>
    </dl>
    <h3>
      <font color="blue">Examples</font>
    </h3>
    <pre>

//SCHUR FORM OF A MATRIX
//----------------------
A=diag([-0.9,-2,2,0.9]);X=rand(A);A=inv(X)*A*X;
[U,T]=schur(A);T

[U,dim,T]=schur(A,'c');
T(1:dim,1:dim)      //stable cont. eigenvalues

function t=mytest(Ev),t=abs(Ev)&lt;0.95,endfunction
[U,dim,T]=schur(A,mytest);
T(1:dim,1:dim)  

// The same function in C (a Compiler is required)
C=['int mytest(double *EvR, double *EvI) {' //the C code
   'if (*EvR * *EvR + *EvI * *EvI &lt; 0.9025) return 1;'
   'else return 0; }';]
mputl(C,TMPDIR+'/mytest.c')


//build and link
lp=ilib_for_link('mytest','mytest.o',[],'c',TMPDIR+'/Makefile');
link(lp,'mytest','c'); 

//run it
[U,dim,T]=schur(A,'mytest');
//SCHUR FORM OF A PENCIL
//----------------------
F=[-1,%s, 0,   1;
    0,-1,5-%s, 0;
    0, 0,2+%s, 0;
    1, 0, 0, -2+%s];
A=coeff(F,0);E=coeff(F,1);
[As,Es,Q,Z]=schur(A,E);
Q'*F*Z //It is As+%s*Es


[As,Es,Z,dim] = schur(A,E,'c')
function t=mytest(Alpha,Beta),t=real(Alpha)&lt;0,endfunction
[As,Es,Z,dim] = schur(A,E,mytest)

//the same function in Fortran (a Compiler is required)
ftn=['integer function mytestf(ar,ai,b)' //the fortran code
      'double precision ar,ai,b'
      'mytestf=0'
      'if(ar.lt.0.0d0) mytestf=1'
      'end']
mputl('      '+ftn,TMPDIR+'/mytestf.f')

//build and link
lp=ilib_for_link('mytestf','mytestf.o',[],'F',TMPDIR+'/Makefile');
link(lp,'mytestf','f'); 

//run it

[As,Es,Z,dim] = schur(A,E,'mytestf')
 
  </pre>
    <h3>
      <font color="blue">See Also</font>
    </h3>
    <p>
      <a href="spec.htm">
        <tt>
          <b>spec</b>
        </tt>
      </a>,&nbsp;&nbsp;<a href="bdiag.htm">
        <tt>
          <b>bdiag</b>
        </tt>
      </a>,&nbsp;&nbsp;<a href="../control/ricc.htm">
        <tt>
          <b>ricc</b>
        </tt>
      </a>,&nbsp;&nbsp;<a href="pbig.htm">
        <tt>
          <b>pbig</b>
        </tt>
      </a>,&nbsp;&nbsp;<a href="psmall.htm">
        <tt>
          <b>psmall</b>
        </tt>
      </a>,&nbsp;&nbsp;</p>
  </body>
</html>
